home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 May / EnigmA AMIGA RUN 18 (1997)(G.R. Edizioni)(IT)[!][issue 1997-05][EAR-CD II].iso / softwareupdate / system / amigados / parsingcommandline / functions.doc < prev    next >
Text File  |  1996-10-10  |  14KB  |  368 lines
  1. 5  PARSING THE COMMAND LINE - FUNCTIONS
  2.  
  3. 5  QUICK REFERENCE
  4.  
  5. Here is a complete list of all parsing routines:
  6.  
  7.   Function      Description                                   
  8.   -------------------------------------------------------------
  9.   FindArg()     Looks for names in a command line template
  10.   FreeArgs()    Deallocates memory after ReadArgs()
  11.   ReadArgs()    Parses the command line or a user string
  12.   ReadItem()    Collects arguments from command line or string
  13.   -------------------------------------------------------------
  14.  
  15.  
  16.  
  17. ---------------------------------------------------------------
  18.  
  19. FindArg()
  20.  
  21. ROM library: "dos.library/FindArg", (V36+)
  22. #include <clib/dos_protos.h>
  23.  
  24. Examines a command line template and looks for a specified
  25. command template name. Returns the command template position,
  26. or -1 if the command template name could not be found.
  27.  
  28. Synopsis: position = FreeArgs( name, template );
  29.  
  30.   position: (LONG) If the function finds the command template
  31.             it will return the command template's position
  32.             in the complete command line template. If the
  33.             command template could not be found -1 is returned.
  34.  
  35.   name:     (STRPTR) Pointer to a string containing the name
  36.             of the command template you want to look for.
  37.  
  38.   template: (STRPTR) Pointer to a string containing the
  39.             command line template you want to search in.
  40.  
  41. Here is a simple example on how to use the FindArg() function:
  42. ("SoundFiles" has the position 0, "Volume" position 1, and
  43. "Filter" position 2.)
  44.  
  45.   #define MY_TEMPLATE "SoundFiles/M/A,V=Volume/K/N,F=Filter/S"
  46.  
  47.   /* Store the command template position here: */
  48.   int template_position;
  49.  
  50.   - - -
  51.  
  52.   /* Which position has the comman template "Filter"? */
  53.   template_position = FindArg( MY_COMMAND_LINE_TEMPLATE, "Filter" );
  54.  
  55.   /* Print the position: */
  56.   printf( "Position %d\n", template_position );
  57.  
  58.  
  59. See also: AllocDosObject(), FreeArgs(), FreeDosObject(),
  60.           ReadArgs(), ReadItem()
  61.  
  62. ---------------------------------------------------------------
  63.  
  64. FreeArgs()
  65.  
  66. ROM library: "dos.library/FreeArgs", (V36+)
  67. #include <clib/dos_protos.h>
  68.  
  69. Deallocates the memory that was allocated when you successfully
  70. called the ReadArgs() function.
  71.  
  72. Synopsis: FreeArgs( rdargs );
  73.  
  74.   retrda: (struct RDArgs *) Pointer to the RDArgs structure
  75.           that was returned when you successfuly called
  76.           ReadArgs().
  77.           
  78.           If you have allocated the RDArgs structure yourself
  79.           only the collected arguments will be deallocated. The
  80.           structure itself must then be deallocated with help
  81.           of the FreeDosObject() function.
  82.           
  83.           If you did not allocate the RDArgs structure (it was
  84.           automatically allocated by the ReadArgs() function)
  85.           the structure as well as the data for the arguments
  86.           will be deallocated. 
  87.  
  88. Please remember that before your program terminates you must
  89. always call FreeArgs() if you have successfully used
  90. ReadArgs(), even if you have allocated the RDArgs structure
  91. yourself.
  92.  
  93. Here is a simple example on how to use the FreeArgs() function:
  94.  
  95.   /* Store the returned RDArgs pointer here: */
  96.   struct RDArgs *returned_rdargs;
  97.  
  98.   - - -
  99.  
  100.   /* Parse the command line: */
  101.   returned_rdargs = ReadArgs( MY_TEMPLATE, arg_array, NULL );
  102.  
  103.   - - -
  104.  
  105.   /* Free the arguments: */
  106.   FreeArgs( my_rdargs );
  107.  
  108.  
  109. See also: AllocDosObject(), FindArg(), FreeDosObject(),
  110.           ReadArgs(), ReadItem()
  111.  
  112. ---------------------------------------------------------------
  113.  
  114. ReadArgs()
  115.  
  116. ROM library: "dos.library/ReadArgs", (V37+)
  117. #include <clib/dos_protos.h>
  118.  
  119. Parses the command line or an own defined command string with
  120. the help of a command line template.
  121.  
  122. Synopsis: retrda = ReadArgs( cltemplate, arg_array, rdargs );
  123.  
  124.   retrda:     (struct RDArgs *) If the function could
  125.               successfully parse the command line (or our own
  126.               command string) it returns a pointer to a
  127.               RDArgs structure. If we supplied the function
  128.               with our own RDArgs structure, this pointer will
  129.               simply point to our structure. On the other hand,
  130.               if we did not supply the function with an already
  131.               created RDArgs structure the function will have
  132.               created one for us.
  133.               
  134.               If this function manages to parse the command
  135.               line (or our own command string), regardless if
  136.               you have created the RDArgs structure yourself or
  137.               not, you must call the FreeArgs() function when
  138.               you do not need to use the collected arguments
  139.               any more. (If you allocated the RDArgs structure
  140.               yourself you must then also free it yourself
  141.               with help of the FreeDosObject() function.)
  142.               
  143.               If the function fails to parse the command line
  144.               (or our own command string) it returns NULL.
  145.  
  146.   cltemplate: (STRPTR) Pointer to a sting which contains our
  147.               "command line template". Each "command template"
  148.               is written like this:
  149.               
  150.               [<abbreviation>=]TemplateName[option(s)]
  151.  
  152.               First there is the optional abbreviation, then
  153.               comes the name of this command template, and
  154.               finally zero or more of the following options:
  155.               (See chapter document for more information about
  156.               the comman templates.)
  157.  
  158.                 Option  Description
  159.                 ----------------------------------
  160.                   /A    Always required argument
  161.                   /F    Final argument of the line
  162.                   /K    Keyword is required
  163.                   /M    Multiple arguments
  164.                   /N    Number argument
  165.                   /S    Switch argument
  166.                   /T    Toggle argument
  167.  
  168.               If there are more than one command template they
  169.               must be separated with commas. No spaces are
  170.               allowed. Please note that the parse functions are
  171.               not case sensetive, the small "a" is equal to the
  172.               captial "A".
  173.  
  174.   arg_array:  (LONG *) You must give the function an array of
  175.               "LONG" variables, with at least one entry (LONG
  176.               variable) for every command template. If the
  177.               function manages to parse the command line (or
  178.               ur our own command string) the result of each
  179.               command template will be placed in the
  180.               corresponding position in array. (The result of
  181.               the first command template will be placed in
  182.               position 0 of the array, the second command
  183.               template will be placed in position 1 in the
  184.               array, and so on... 
  185.  
  186.               Note! The array must have one entry (one LONG
  187.               variable) for every comman template! The function
  188.               will not check the size of the array before it
  189.               stores the result in it.
  190.  
  191.               What type of values that will be stored in the
  192.               array depends on what type of command templates
  193.               are used.
  194.               
  195.               1. The default is that the array will contain a
  196.               pointer to a string where a copy of the
  197.               corresponding argument is placed. If no argument
  198.               of this type was entered the pointer will be
  199.               NULL. (Remember to check that the pointer really
  200.               points to a string before you try to examine the
  201.               string! If the "/A" option was used together with
  202.               this template we know that the pointer must point
  203.               to a string since this argument was required, and
  204.               the function would have failed if this argument
  205.               was not included. However, it it best to always
  206.               check the string that it does not point to NULL
  207.               before you use it!)
  208.               
  209.               2. If the "/M" (multiple arguments) option was
  210.               used there may be zero or more arguments that
  211.               fitted this template. The LONG value in the array
  212.               will therefore consist of a pointer to an array
  213.               of strings, where the last string pointer is set
  214.               to NULL.
  215.               
  216.               3. If the "/N" (numeric argument) option was used
  217.               the LONG variable in the array will contain a
  218.               pointer to the value, or be NULL if no value was
  219.               entered.
  220.               
  221.               4. Finally there exist the switches "/S" (or
  222.               "flags" as they are sometimes called). If the
  223.               switch was set the variable in the array will be
  224.               non-zero. If the switch was not set the value
  225.               will be 0. If you used the "/T" switch the value
  226.               in the array will toggle if the argument was set.
  227.               (If the value in the array was 0 it will be
  228.               toggled to a non-zero value, and if the value
  229.               was non-zero it will be togled to 0.)
  230.  
  231.   rdargs:     (struct RDArgs *) If you want to set some special
  232.               flags or parse your own command string (instead
  233.               of the default command line) you should create a
  234.               RDArgs structure yourself and prepare it as
  235.               desired, before you call this function and pases
  236.               a pointer to the structure. However, if you want
  237.               to parse the command line and do not want to set
  238.               any special flags you simply write NULL.
  239.  
  240. Note that if this function could successfully parse the command
  241. line you have to call the FreeArgs() function later on when you
  242. do not need the arguments any more. This must be done regardles
  243. of you have created the RDArgs structure yourself or not.
  244.  
  245. When the ReadArgs() function successfully manages to parse a
  246. command line (or our own command string) it will allocate some
  247. memory where the result (data) will be stored. Remember that the
  248. array you use only contains pointers to the data, and it is this
  249. data areas that must be deallocated. If the ReadArgs() function
  250. fails it will have not allocated any memory to store the data
  251. in, and consequently you do not have to call the FreeArgs()
  252. function.
  253.  
  254. Here is a simple example on how to use the ReadArgs() function:
  255.  
  256.   #define MY_TEMPLATE "SoundFiles/M/A,V=Volume/K/N,F=Filter/S"
  257.  
  258.   /* Store the returned RDArgs pointer here: */
  259.   struct RDArgs *returned_rdargs;
  260.  
  261.   - - -
  262.  
  263.   /* Parse the command line: */
  264.   returned_rdargs = ReadArgs( MY_TEMPLATE, arg_array, NULL );
  265.  
  266.   /* Could we parse the command line? */
  267.   if( returned_rdargs )
  268.   {
  269.     printf( "The command line successfully parsed!\n" );
  270.     
  271.     /* Examine the arg_array to see what arguments were set: */
  272.   }
  273.   else
  274.     printf( "Could not parse the command line!\n" );
  275.  
  276.  
  277. See also: AllocDosObject(), FindArg(), FreeArgs(),
  278.           FreeDosObject(), ReadItem()
  279.  
  280. ---------------------------------------------------------------
  281.  
  282. ReadItem()
  283.  
  284. ROM library: "dos.library/ReadItem", (V36+)
  285. #include <clib/dos_protos.h>
  286.  
  287. Collects one argument from the command line or our own command
  288. string.
  289.  
  290. Synopsis: item = ReadItem( buffer, size, source );
  291.  
  292.   item:   (LONG) The function will return a value which tells
  293.           us what type of argument that was collected. For
  294.           the moment these types of items can be identified:
  295.           (defined in headerfile "dos/dos.h")
  296.           
  297.             ITEM_NOTHING  Nothing found, no more arguments
  298.                           (items) in the command line/string.
  299.  
  300.             ITEM_UNQUOTED The collected argument (item) was not
  301.                           surrounded by quotation marks.
  302.  
  303.             ITEM_QUOTED   The collected argument was surrounded
  304.                           by quotation marks.
  305.  
  306.             ITEM_EQUAL    The collected argument was an equal
  307.                           sign (=).
  308.  
  309.             ITEM_ERROR    There was a problem, could not
  310.                           collect the argument.
  311.           
  312.   buffer: (STRPTR) Pointer to some memory where the collected
  313.           argument can be stored.
  314.  
  315.   size:   (LONG) The size of the memory where the collected
  316.           argument will be stored. 
  317.  
  318.   source: (struct CSource *) If you want to collect the
  319.           argument from the command line set this field to
  320.           NULL. If you want to collect the argument from a
  321.           a string you have created yourself give this field
  322.           a pointer to a CSource structure which you have
  323.           prepared with the command string you want to use.
  324.  
  325. Here is a simple example on how to collect all arguments from
  326. the command line:
  327.  
  328.   /* Store up to 50 characters in our string buffer: */
  329.   #define BUFFER_SIZE 50
  330.  
  331.   /* Store the argument (item) type value here: */
  332.   LONG item_type;
  333.  
  334.   /* Temporary string buffer to store the argument name in: */
  335.   UBYTE item_name[ BUFFER_SIZE ];
  336.  
  337.   - - -
  338.  
  339.   /* Collect the first argument: */
  340.   item_type = ReadItem( item_name, BUFFER_SIZE, NULL );
  341.  
  342.   /* As long as we find arguments we stay in the while loop: */
  343.   while( item_type )
  344.   {
  345.     /* Print the item type: */    
  346.     switch( item_type )
  347.     {
  348.       case ITEM_EQUAL:    printf( "Equal symbol  " ); break;
  349.       case ITEM_ERROR:    printf( "Item ERROR    " ); break;
  350.       case ITEM_UNQUOTED: printf( "Unquoted item " ); break;
  351.       case ITEM_QUOTED:   printf( "Quoted item   " ); break;
  352.       default:            printf( "Unknown item! " );
  353.     }
  354.  
  355.     /* Print the item string: */
  356.     printf( "%s\n", item_name );
  357.     
  358.     /* Collect next item: */    
  359.     item_type = ReadItem( item_name, BUFFER_SIZE, NULL );
  360.   }
  361.  
  362.  
  363. See also: AllocDosObject(), FindArg(), FreeArgs(),
  364.           FreeDosObject(), ReadArgs()
  365.  
  366. ---------------------------------------------------------------
  367.  
  368.